Common Properties, Methods and Events

This appendix contains the reference for all the properties and methods common to most of the ProtoView Controls and ActiveX controls in general. Each property and method will list exactly which controls support that method.

Common Properties

Introduction

Many properties are common to most or all the ProtoView Controls, and are common to most ActiveX controls in general. Rather than list the details of these methods for each control, these common properties have been collected in a single reference area. Note not every ProtoView Control will support all the properties listed here.

Appearance

Returns or sets the paint style of a ProtoView Control object. Read only at run time.

Syntax

Visual Basic

object.Appearance = value
value = object.Appearance

Visual C++

object.SetAppearance(value);
value = object.GetAppearance( );

Delphi

object.Appearance := value;
value := object.Appearance;

The Appearance property syntax has these parts:

Settings

The settings for value are:

Remarks

If set to 1 at design time, the Appearance property draws the control with three-dimensional effects. Setting the Appearance property to 1 also disables the BorderStyle property.

BackColor

BackColor returns or sets the background color of a ProtoView Control object.

Syntax

Visual Basic

object.BackColor = color
color = object.BackColor

Visual C++

object.SetBackColor(color);
color = object.GetBackColor( );

Delphi

object.BackColor:= color;
color:= object.BackColor;

The BackColor property syntax has these parts:

Settings

See the section Notes About Colors in this chapter.

Remarks

See the section Notes About Colors in this chapter

BorderStyle

Returns or sets the border style for a ProtoView Control object, read only at run time.

Syntax

Visual Basic

object.BorderStyle = value
value = object.BorderStyle

Visual C++

object.SetBorderStyle(value);
value = object.GetBorderStyle( );

Delphi

object.BorderStyle:= value;
value:= object.BorderStyle;

The BorderStyle property syntax has these parts:

Settings

The settings for value are:

Remarks

The BorderStyle property is not active unless the Appearance property is set to 0.

Enabled

Returns or sets a value that determines whether a ProtoView Control object can respond to user-generated events.

Syntax

Visual Basic

object.Enabled = boolean
boolean = object.Enabled

Visual C++

object.SetEnabled(boolean);
boolean = object.GetEnabled( );

Delphi

object.Enabled:= boolean;
boolean:= object.Enabled;

The Enabled property syntax has these parts:

Settings

The settings for boolean are:

Remarks

The Enabled property allows forms and controls to be enabled or disabled at run time. For example, you can disable objects that don't apply to the current state of the application. You can also disable a control used purely for display purposes, such as a text box that provides read-only information.

Font

Returns a Font object.

Syntax

Visual Basic

object.Font = font
font = object.Font

Visual C++

object.SetFont(font);
font = object.GetFont( );

Delphi

object.Font:= font;
font:= object.Font;

The Font property syntax has these parts:

Remarks

Use the Font property of an object to identify a specific Font object whose properties you want to use. For example, the following code changes the Bold property setting of a Font object identified by the Font property of a TextBox object:

Visual Basic Example

txtFirstName.Font.Bold = True

Visual C++ Example

pIOleFont->SetBold(TRUE);
txtFirstName.SetFont(pIOleFont);

ForeColor

ForeColor returns or sets the foreground color used to display text and graphics in to a ProtoView Control object.

Syntax

Visual Basic

object.ForeColor = color
color = object.ForeColor

Visual C++

object.SetForeColor(color);
color = object.GetForeColor( );

Delphi

object.ForeColor:= color;
color:= object.ForeColor;

The ForeColor property syntax has these parts:

Settings

See the section Notes About Colors in this chapter.

Remarks

See the section Notes About Colors in this chapter.

GetCaretPosition

This method returns the zero-based index of the caret within the text of an editable component.

Syntax

Visual Basic

ReturnValue = object.GetCaretPosition

C++

ReturnValue = object.GetCaretPosition ( );

Delphi

ReturnValue := object.GetCaretPosition()

The GetCaretPosition method syntax has these parts:

GetEndSelection

This method returns the zero-based index of the last selected character within the text of an editable component.

Syntax

Visual Basic

ReturnValue = object.GetEndSelection

C++

ReturnValue = object.GetEndSelection ( );

Delphi

ReturnValue := object.GetEndSelection()

The GetEndSelection method syntax has these parts:

GetStartSelection

This method returns the zero-based index of the first selected character within the text of an editable component.

Syntax

Visual Basic

ReturnValue = object.GetStartSelection

C++

ReturnValue = object.GetStartSelection ( );

Delphi

ReturnValue := object.GetStartSelection()

The GetStartSelection method syntax has these parts:

hWnd

Returns a handle to a ProtoView Control object. Read-only at run time, not available at design time.

Syntax

Visual Basic

hWnd = object.hWnd

Visual C++

hWnd = object.GethWnd( );

Delphi

hWnd:= object.hWnd;

The hWnd property syntax has these parts:

Remarks

The Microsoft Windows operating environment identifies each form and control in an application by assigning it a handle, or hWnd. The hWnd property is used with Windows API calls. Many Windows operating environment functions require the hWnd of the active window as an argument.

Note Because the value of this property can change while a program is running, never store the hWnd value in a variable.

ValidateLimit

Returns or sets how strict a control will enforce upper and lower limits.

Syntax

Visual Basic

object.ValidateLimit = value
value = object.ValidateLimit

Visual C++

object.SetValidateLimit(value);
value = object.GetValidateLimit( );

Delphi

object.ValidateLimit:= value;
value:= object.ValidateLimit;

The ValidateLimit property syntax has these parts:

Settings

The settings for value are:

Remarks

If the component validates the upper and lower limits before each keystroke, the control will beep and prevent entry of a value that will violate the limit.  For example, if you have 10000 as an upper limit and the control is currently displaying 9000, the control will prevent the addition of a fifth digit.  If you set a lower limit 10 or above, then you will be unable to hightlight the controls contents and enter a new value, since any digit entered will be less than 10.

Notes about Colors

Visual Basic uses the Microsoft Windows operating environment red-green-blue (RGB) color scheme. The settings for color are:

For all forms and controls, the default settings at design time are:

BackColor set to the system default color specified by the constant vbWindowBackground.

ForeColor set to the system default color specified by the constant vbWindowText.

The valid range for a normal RGB color is 0 to 16,777,215 (&HFFFFFF). The high byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte isn't 0, Visual Basic uses the system colors, as defined in the user's the Control Panel settings and by constants listed in the Visual Basic (VB) object library in the Object Browser.

To display text in the Windows operating environment, both the text color must be solid. If the text color you've selected isn’t displayed, the selected colors may be dithered, that is, comprised of up to three different-colored pixels. If you choose a dithered color for the text, the nearest solid color will be substituted.

Common Methods

Introduction

Many methods are common to most or all the ProtoView Controls, and are common to most ActiveX controls in general. Rather than list the details of these methods for each control, these common properties have been collected in a single reference area. Note not every ProtoView Control will support all the methods listed here.

AboutBox

Use the AboutBox command to find the version number and other pertinent information about WinX.

Syntax

Visual Basic

object.AboutBox

Visual C++

object. AboutBox();

Delphi

object. AboutBox;

The AboutBox method syntax has these parts:

Common Events

Introduction

Many events are common to most or all the ProtoView Controls, and are common to most ActiveX controls in general. Rather than list the details of these events for each control, these common events have been collected in a single reference area. Note not every ProtoView Control will support all the events listed here.

Click

Occurs when the user presses and then releases a mouse button a ProtoView Control object. It can also occur when the value of a ProtoView Control object is changed.

Syntax

Visual Basic

Private Sub Object_Click([index As Integer])

Visual C++

void OnClickObject();

Delphi

Procedure Click(Sender : TObject)

The Click event syntax has these parts:

Remarks

For a control, this event occurs when the user:

Clicks a control with the left or right mouse button. With a 3D check box, 3D command button, or 3D option button control, the Click event occurs only when the user clicks the left mouse button.

Presses the SPACEBAR when a 3D command button, 3D option button, or 3D check box control has the focus.

Presses ENTER when a form has a 3D command button control with its Default property set to True.

Presses ESC when a form has a Cancel buttonfor example, a 3D command button control with its Cancel property set to True.

Presses an access key for a control. For example, if the caption of a 3D command button control is "&Go", pressing ALT+G triggers the event.

Typically, you attach a Click event procedure to a 3D command button control to carry out commands and command-like actions. For the other applicable controls, use this event to trigger actions in response to a change in the control.

Note To distinguish between the left, right, and middle mouse buttons, use the MouseDown and MouseUp events.

DblClick

Occurs when the user presses and releases a mouse twice quickly over a ProtoView Control object.

Syntax

Visual Basic

Private Sub Object_DblClick([index As Integer])

Visual C++

void OnDblClickObject();

Delphi

Procedure DblClick(Sender : TObject)

The DblClick event syntax has these parts:

Remarks

The argument Index uniquely identifies a control if it's in a control array. You can use a DblClick event procedure for an implied action, such as double-clicking an icon to open a window or document. You can also use this type of procedure to carry out multiple steps with a single action, such as double-clicking to select an item in a list box and to close the dialog box.

For those objects that receive Mouse events, the events occur in this order: MouseDown, Click, MouseUp, and DblClick.

If DblClick doesn't occur within the system's double-click time limit, the object recognizes another Click event. The double-click time limit may vary because the user can set the double-click speed in the Control Panel. When you're attaching procedures for these related events, be sure that their actions don't conflict.

Note To distinguish between the left, right, and middle mouse buttons, use the MouseDown and MouseUp events.

KeyDown

Fired each time a key is pressed when a ProtoView Control object has input focus.

Syntax

Visual Basic

Private Sub Object_KeyDown([index As Integer], KeyCode As Integer, Shift As Integer)

Visual C++

void OnKeyDownObject(short KeyCode, short Shift);

Delphi

Procedure KeyDown(Sender : TObject, KeyCode : Integer, Shift : Integer)

The KeyDown event syntax has these parts:

Remarks

The object with the focus receives all keystrokes. Although the KeyDown and KeyUp events can apply to most keys, they're most often used for:

Extended character keys such as function keys.

Navigation keys.

Combinations of keys with standard keyboard modifiers.

Distinguishing between the numeric keypad and regular number keys.

Use KeyDown and KeyUp event procedures if you need to respond to both the pressing and releasing of a key.

KeyDown and KeyUp aren't invoked for:

The ENTER key if the form has a 3D command button control with the Default property set to True.

The ESC key if the form has a 3D command button control with the Cancel property set to True.

The TAB key.

KeyDown and KeyUp interpret the uppercase and lowercase of each character by means of two arguments: KeyCode, which indicates the physical key (thus returning A and a as the same key) and Shift, which indicates the state of shift+key and therefore returns either A or a.

If you need to test for the Shift argument, you can declare constants that define the bits within the argument by using constants listed in the object library in the Object Browser. The shift constants have the following values:

The constants act as bit masks that you can use to test for any combination of keys. Place the constants at the procedure level or in the Declarations section of a module and use this syntax:

Const constantname = expression

You test for a condition by first assigning each result to a temporary integer variable and then comparing Shift to a bit mask. Use the And operator with the Shift argument to test whether the condition is greater than 0, indicating that the modifier was pressed, for example:

ShiftDown = (Shift And vbShiftMask) > 0

In a procedure, you can test for any combination of conditions, for example:

If ShiftDown And CtrlDown Then

Note If the KeyPreview property is set to True, a form receives these events before controls on the form receive the events. Use the KeyPreview property to create global keyboard-handling routines.

KeyPress

Fired each time a key is pressed when a ProtoView Control object has input focus.

Syntax

Visual Basic

Private Sub Object_KeyPress([index As Integer], KeyAscii As Integer)

Visual C++

void OnKeyPressObject(short FAR* KeyAscii);

Delphi

Procedure KeyPress(Sender : TObject, var KeyAscii: Integer)

The KeyPress event syntax has these parts:

Remarks

The object with the focus receives the event. A form can receive the event only if it has no visible and enabled controls or if the KeyPreview property is set to True. A KeyPress event can involve any printable keyboard character, the CTRL key combined with a character from the standard alphabet or one of a few special characters, and the ENTER or BACKSPACE key. Changing the value of the KeyAscii argument changes the character displayed.

You can convert the KeyAscii argument into a character by using the expression:

Chr(KeyAscii)

You can then perform string operations and translate the character back to an ANSI number that the control can interpret by using the expression:

KeyAscii = Asc(char)

Use KeyDown and KeyUp event procedures to handle any keystroke not recognized by KeyPress, such as function keys, editing keys, navigation keys, and any combinations of these with keyboard modifiers. Unlike the KeyDown and KeyUp events, KeyPress doesn't indicate the physical state of the keyboard; instead, it passes a character.

KeyPress interprets the uppercase and lowercase of each character as separate key codes and, therefore, as two separate characters. KeyDown and KeyUp interpret the uppercase and lowercase of each character by means of two arguments: keycode, which indicates the physical key (thus returning A and a as the same key), and shift, which indicates the state of shift+key and therefore returns either A or a.

If the KeyPreview property is set to True, a form receives the event before controls on the form receive the event. Use the KeyPreview property to create global keyboard-handling routines.

Note The ANSI number for the keyboard combination of CTRL+@ is 0. Because Visual Basic recognizes a KeyAscii value of 0 as a zero-length string (""), avoid using CTRL+@ in your applications.

KeyUp

Fired each time a key is released when a ProtoView Control object has input focus.

Syntax

Visual Basic

Private Sub Object_KeyUp([index As Integer], KeyCode As Integer, Shift As Integer)

Visual C++

void OnKeyUpObject(short KeyCode, short Shift);

Delphi

Procedure KeyUp(Sender : TObject, KeyCode : Integer, Shift : Integer)

The KeyUp event syntax has these parts:

Remarks

The object with the focus receives all keystrokes. Although the KeyDown and KeyUp events can apply to most keys, they're most often used for:

Extended character keys such as function keys.

Navigation keys.

Combinations of keys with standard keyboard modifiers.

Distinguishing between the numeric keypad and regular number keys.

Use KeyDown and KeyUp event procedures if you need to respond to both the pressing and releasing of a key.

KeyDown and KeyUp aren't invoked for:

The ENTER key if the form has a 3D command button control with the Default property set to True.

The ESC key if the form has a 3D command button control with the Cancel property set to True.

The TAB key.

KeyDown and KeyUp interpret the uppercase and lowercase of each character by means of two arguments: KeyCode, which indicates the physical key (thus returning A and a as the same key) and Shift, which indicates the state of shift+key and therefore returns either A or a.

If you need to test for the Shift argument, you can declare constants that define the bits within the argument by using constants listed in the object library in the Object Browser. The shift constants have the following values:

The constants act as bit masks that you can use to test for any combination of keys. Place the constants at the procedure level or in the Declarations section of a module and use this syntax:

Const constantname = expression

You test for a condition by first assigning each result to a temporary integer variable and then comparing Shift to a bit mask. Use the And operator with the Shift argument to test whether the condition is greater than 0, indicating that the modifier was pressed, for example:

ShiftDown = (Shift And vbShiftMask) > 0

In a procedure, you can test for any combination of conditions, for example:

If ShiftDown And CtrlDown Then

Note If the KeyPreview property is set to True, a form receives these events before controls on the form receive the events. Use the KeyPreview property to create global keyboard-handling routines.

MouseDown

Occurs when the user presses (MouseDown) or releases (MouseUp) a mouse button over a ProtoView Control object.

Syntax

Visual Basic

Private Sub Object_MouseDown([index As Integer], Button As Integer, Shift As Integer, x As Single, y As Single)

Visual C++

void OnMouseDownObject(short Button, short Shift, long x, long y);

Delphi

Procedure MouseDown(Sender : TObject, Button : Integer, Shift : Integer, x : Single, y : Single)

The MouseDown event syntax has these parts:

Remarks

Use a MouseDown or MouseUp event procedure to specify actions that will occur when a given mouse button is pressed or released. Unlike the Click and DblClick events, MouseDown and MouseUp events enable you to distinguish between the left, right, and middle mouse buttons. You can also write code for mouse-keyboard combinations that use the SHIFT, CTRL, and ALT keyboard modifiers.

The following applies to both Click and DblClick events:

If a mouse button is pressed while the pointer is over a control, that object "captures" the mouse and receives all mouse events up to and including the last MouseUp event. This implies that the x, y mouse-pointer coordinates returned by a mouse event may not always be in the client area of the object that receives them.

If mouse buttons are pressed in succession, the object that captures the mouse after the first press receives all mouse events until all buttons are released.

If you need to test for the button or shift arguments, you can use constants listed in the object library in the Object Browser to define the bits within the argument:

The constants then act as bit masks you can use to test for any combination of buttons without having to figure out the unique bit field value for each combination.

MouseMove

Occurs when the user moves the mouse over a ProtoView Control object.

Syntax

Visual Basic

Private Sub Object_MouseMove([index As Integer], Button As Integer, Shift As Integer, x As Single, y As Single)

Visual C++

void OnMouseMoveObject(short Button, short Shift, long x, long y);

Delphi

Procedure MouseMove(Sender : TObject, Button : Integer, Shift : Integer, x : Single, y : Single)

The MouseMove event syntax has these parts:

Remarks

The MouseMove event is generated continually as the mouse pointer moves across objects. Unless another object has captured the mouse, an object recognizes a MouseMove event whenever the mouse position is within its borders.

If you need to test for the button or shift arguments, you can use constants listed in the object library in the Object Browser to define the bits within the argument:

The constants then act as bit masks you can use to test for any combination of buttons without having to figure out the unique bit field value for each combination.

You test for a condition by first assigning each result to a temporary integer variable and then comparing the button or shift arguments to a bit mask. Use the And operator with each argument to test if the condition is greater than zero, indicating the key or button is pressed, as in the following code:

LeftDown = (Button And vbLeftButton) > 0

CtrlDown = (Shift And vbCtrlMask) > 0

Then, in a procedure, you can test for any combination of conditions, as follows:

If LeftDown And CtrlDown Then

Note You can use MouseDown and MouseUp event procedures to respond to events caused by pressing and releasing mouse buttons.

The button argument for MouseMove differs from the button argument for MouseDown and MouseUp. For MouseMove, the button argument indicates the current state of all buttons; a single MouseMove event can indicate that some, all, or no buttons are pressed. For MouseDown and MouseUp, the button argument indicates exactly one button per event.

Any time you move a window inside a MouseMove event, it can cause a cascading event. MouseMove events are generated when the window moves underneath the pointer. A MouseMove event can be generated even if the mouse is perfectly stationary.

MouseUp

Occur when the user presses and releases a mouse button over a ProtoView Control object.

Syntax

Visual Basic

Private Sub Object_MouseUp([index As Integer], Button As Integer, Shift As Integer, x As Single, y As Single)

Visual C++

void OnMouseUpObject(short Button, short Shift, long x, long y);

Delphi

Procedure MouseUp(Sender : TObject, Button : Integer, Shift : Integer, x : Single, y : Single)

The MouseUp event syntax has these parts:

Remarks

Use a MouseDown or MouseUp event procedure to specify actions that will occur when a given mouse button is pressed or released. Unlike the Click and DblClick events, MouseDown and MouseUp events enable you to distinguish between the left, right, and middle mouse buttons. You can also write code for mouse-keyboard combinations that use the SHIFT, CTRL, and ALT keyboard modifiers.

The following applies to both Click and DblClick events:

If a mouse button is pressed while the pointer is over a control, that object "captures" the mouse and receives all mouse events up to and including the last MouseUp event. This implies that the x, y mouse-pointer coordinates returned by a mouse event may not always be in the client area of the object that receives them.

If mouse buttons are pressed in succession, the object that captures the mouse after the first press receives all mouse events until all buttons are released.

If you need to test for the button or shift arguments, you can use constants listed in the object library in the Object Browser to define the bits within the argument:

The constants then act as bit masks you can use to test for any combination of buttons without having to figure out the unique bit field value for each combination.